home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / layout.doc < prev    next >
Text File  |  1996-09-05  |  49KB  |  1,446 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/Layout_Routines
  4. dopus5.library/AddObjectList
  5. dopus5.library/AddWindowMenus
  6. dopus5.library/BoundsCheckGadget
  7. dopus5.library/BuildMenuStrip
  8. dopus5.library/CheckObjectArea
  9. dopus5.library/ClearWindowBusy
  10. dopus5.library/CloseConfigWindow
  11. dopus5.library/DisableObject
  12. dopus5.library/DisplayObject
  13. dopus5.library/EndRefreshConfigWindow
  14. dopus5.library/FindMenuItem
  15. dopus5.library/FreeObjectList
  16. dopus5.library/FreeWindowMenus
  17. dopus5.library/GetGadgetValue
  18. dopus5.library/GetObject
  19. dopus5.library/GetObjectRect
  20. dopus5.library/GetWindowAppPort
  21. dopus5.library/GetWindowID
  22. dopus5.library/GetWindowMsg
  23. dopus5.library/LayoutResize
  24. dopus5.library/OpenConfigWindow
  25. dopus5.library/ReplyWindowMsg
  26. dopus5.library/SetConfigWindowLimits
  27. dopus5.library/SetGadgetChoices
  28. dopus5.library/SetGadgetValue
  29. dopus5.library/SetWindowBusy
  30. dopus5.library/SetWindowID
  31. dopus5.library/StartRefreshConfigWindow
  32. dopus5.library/Layout_Routines                 dopus5.library/Layout_Routines
  33.  
  34.     PURPOSE
  35.  
  36. 1.  The dopus5.library provides font-sensitive layout routines to make it
  37. easy to create and use a user interface for your application or module. The
  38. layout code is not as straightforward, or indeed as powerful, as MUI or some
  39. of the other GUI engines available, and so you might want to consider using
  40. one of those instead of the DOpus routines.
  41.  
  42.     The normal procedure in creating an interface is :
  43.  
  44.     1. Define a list of "objects" (gadgets, text, etc)
  45.     2. Define a window
  46.     3. Call OpenConfigWindow() to open the window
  47.     4. Call AddObjectList() to add the objects
  48.     5. Call SetGadgetValue() to initialise gadgets
  49.     6. Message loop with GetWindowMsg()
  50.     7. Call GetGadgetValue() to get gadget final values
  51.     8. Call CloseConfigWindow() to close the window
  52.  
  53.  
  54. 2.  The list of objects is defined as an array of ObjectDef structures.
  55. You call AddObjectList() to add a list of objects to a window; indeed, you
  56. can make multiple calls to this function to add multiple lists. Each ObjectDef
  57. structure is defined as follows:
  58.  
  59.         od_Type
  60.  
  61.         This field indicates the type of object. Current values are :
  62.  
  63.             OD_GADGET       - a gadget
  64.             OD_TEXT         - a text string
  65.             OD_AREA         - a rectangular area
  66.             OD_IMAGE        - an image
  67.  
  68.         Two control values are also used:
  69.  
  70.             OD_SKIP         - skip this entry
  71.             OD_END          - ends an ObjectDef array
  72.  
  73.  
  74.         od_ObjectKind
  75.  
  76.         If od_Type is set to OD_GADGET, this field describes the type of
  77.         gadget. Valid types are:
  78.  
  79.             BUTTON_KIND         - standard push button
  80.             STRING_KIND         - a string gadget
  81.             INTEGER_KIND        - an integer gadget
  82.             HOTKEY_KIND         - a hotkey field
  83.             CHECKBOX_KIND       - a checkbox gadget
  84.             OPUS_LISTVIEW_KIND  - an Opus listview gadget
  85.             PALETTE_KIND        - a palette gadget (pen selection)
  86.             FILE_BUTTON_KIND    - a button that opens a file requester
  87.             DIR_BUTTON_KIND     - a button that opens a directory requester
  88.             FONT_BUTTON_KIND    - a button that opens a font requester
  89.                                   (only works under v38 ASL)
  90.             FRAME_KIND          - a frame (rectangular area)
  91.             FIELD_KIND          - a readonly string gadget
  92.             NUMBER_KIND         - a number display
  93.             TEXT_KIND           - a text display
  94.  
  95.         The above gadgets are all implemented by the dopus5.library. Many are
  96.         similar to their GadTools equivalents. Any GadTools gadget that is not
  97.         replaced by the above types is also available. Currently, these are:
  98.  
  99.             LISTVIEW_KIND       - standard GadTools listview
  100.             MX_KIND             - radio buttons gadget
  101.             CYCLE_KIND          - cycle gadget
  102.             SCROLLER_KIND       - scroller gadget
  103.             SLIDER_KIND         - slider gadget
  104.  
  105.         If od_Type is OD_AREA or OD_TEXT, the od_ObjectKind field is used to
  106.         specify the pen used for text rendering. This is not a literal pen
  107.         number but is a DrawInfo pen index (eg TEXTPEN).
  108.  
  109.  
  110.         od_CharDims
  111.  
  112.         This field structure is used to define the character position of the
  113.         object. All objects (and windows, for that matter) have two sets of
  114.         positioning information - character and fine. The character position
  115.         is used to specify the size and position in "font units" - this value
  116.         is scaled for the current font and so allows the display to be
  117.         font-sensitive. A "font unit" is the average width of the font for
  118.         a horizontal coordinate, and the height of the font for a vertical
  119.         coordinate. The "Left" and "Top" fields of the IBox structure control
  120.         the position of the object, and the "Width" and "Height" fields control
  121.         the size.
  122.  
  123.         There are some magic values for object positioning and sizing. The
  124.         positioning values are:
  125.  
  126.             POS_CENTER          - use this in the "Left" or "Top" field to have
  127.                                   the object positioned in the center of the
  128.                                   window.
  129.  
  130.             POS_RIGHT_JUSTIFY   - position relative to the right/bottom border
  131.  
  132.         POS_CENTER is an absolute value. POS_RIGHT_JUSTIFY is more of a flag,
  133.         used in conjunction with another value. For example, POS_RIGHT_JUSTIFY
  134.         by itself would position an object hard up against the right border.
  135.         POS_RIGHT_JUSTIFY-2 would position an object at a two 'font unit'
  136.         margin from the border.
  137.  
  138.         The magic values for sizes are:
  139.  
  140.             SIZE_MAXIMUM        - the object will be the maximum possible size
  141.                                   in this direction
  142.  
  143.             SIZE_MAX_LESS       - maximum possible size minus an amount
  144.  
  145.         For example, od_CharDims might be defined as:
  146.  
  147.             {POS_CENTER,POS_RIGHT_JUSTIFY-1,SIZE_MAX_LESS-4,2}
  148.  
  149.         This would create an object that was centered in the display, and as
  150.         wide as possible with a two space gap on either side. The object would
  151.         be one space from the bottom border, and be two spaces high.
  152.  
  153.  
  154.         od_FineDims
  155.  
  156.         This field structure is used to define the fine position and size of
  157.         the object. The fine position is given as an absolute pixel value, and
  158.         allows you to make adjustments for GUI components that do not scale
  159.         with the font (eg, borders are always 1 or 2 pixels high, irrespective
  160.         of the font size). You can also make fine adjustments through this
  161.         field when the od_CharDims field uses the POS_ and SIZE_ values.
  162.  
  163.  
  164.         od_GadgetText
  165.  
  166.         This is the locale string ID for the gadget label, or text or area
  167.         string. It must be a valid ID in the locale specified in the
  168.         NewConfigWindow structure. If the TEXTFLAG_TEXT_STRING flag is set
  169.         for this object, the od_GadgetText field is a pointer to an actual
  170.         text string.
  171.  
  172.  
  173.         od_Flags
  174.  
  175.         The object flags are heavily object dependent. For standard GadTools
  176.         gadgets, the standard GadTools flags apply. Some GadTools flags are
  177.         also applicable to Opus gadgets:
  178.  
  179.             PLACETEXT_LEFT
  180.             PLACETEXT_RIGHT
  181.             PLACETEXT_ABOVE (only works for some gadgets)
  182.             PLACETEXT_IN    (only works for some gadgets)
  183.  
  184.         General purpose Opus flags are:
  185.  
  186.             TEXTFLAG_TEXT_STRING - this flag is used with all the object
  187.             types, and indicates that the od_GadgetText field of the ObjectDef
  188.             structure points to a literal text string and not a locale ID.
  189.  
  190.             TEXTFLAG_NO_USCORE - if you specify this flag, an underscore
  191.             character in the string will be treated literally. Otherwise,
  192.             the underscore is used to specify a character to be underscored,
  193.             indicating a keyboard equivalent.
  194.  
  195.         Flags for BUTTON_KIND gadgets:
  196.  
  197.             BUTTONFLAG_OKAY_BUTTON - indicates that this button is an "ok"
  198.             button. The 'enter' key will automatically be used as a key
  199.             equivalent for this button. The label for this button is
  200.             automatically rendered in bold.
  201.  
  202.             BUTTONFLAG_CANCEL_BUTTON - indicates that this button is a
  203.             "cancel" button. The 'escape' key will automatically be used as a
  204.             key equivalent for this button.
  205.  
  206.             BUTTONFLAG_TOGGLE_SELECT - specifies that you want a toggle-select
  207.             button (one that can be turned on or off).
  208.  
  209.             BUTTONFLAG_THIN_BORDERS - specifies that you want 'thin' borders
  210.             for the button. Thin borders are one pixel wide on all sides,
  211.             whereas normal borders are two pixels wide on the left and right,
  212.             and one pixel wide at the top and bottom. This flag can also
  213.             be used with CHECKBOX_KIND, FRAME_KIND, NUMBER_KIND, TEXT_KIND,
  214.             PALETTE_KIND, FILE_BUTTON_KIND, DIR_BUTTON_KIND and
  215.             FONT_BUTTON_KIND gadgets.
  216.  
  217.         Flags for OPUS_LISTVIEW_KIND gadgets:
  218.  
  219.             LISTVIEWFLAG_CURSOR_KEYS - specifies that the cursor keys can
  220.             be used to scroll up and down in this listview.
  221.  
  222.         Flags for FILE_BUTTON_KIND gadgets:
  223.  
  224.             FILEBUTFLAG_SAVE - specifies that the file requester is to be
  225.             opened in save mode.
  226.  
  227.         Flags for OD_TEXT objects:
  228.  
  229.             TEXTFLAG_RIGHT_JUSTIFY - right justify the text
  230.             TEXTFLAG_CENTER        - center the text
  231.  
  232.         Flags for OD_AREA objects:
  233.  
  234.             AREAFLAG_RAISED - a raised rectangle
  235.             AREAFLAG_RECESSED - a recessed rectangle
  236.             AREAFLAG_THIN - draw rectangle with thin borders
  237.             AREAFLAG_ICON - draw an icon drop box
  238.             AREAFLAG_ERASE - erase the interior of the rectangle
  239.             AREAFLAG_LINE - draw a separator line
  240.             AREAFLAG_OPTIM - optimised refreshing when updating
  241.             AREAFLAG_TITLE - draw a group box with a title
  242.             AREAFLAG_NOFILL - don't fill interior
  243.  
  244.  
  245.         od_ID
  246.  
  247.         This is the ID of the object. If the object is a gadget, it will
  248.         also set the gadget ID.
  249.  
  250.  
  251.         od_TagList
  252.  
  253.         Object-specific taglist. For GadTools gadgets, all the standard
  254.         GadTools flags apply.
  255.  
  256.             GTCustom_LocaleLabels - (USHORT *)
  257.  
  258.             Used with : MX_KIND, CYCLE_KIND
  259.  
  260.             This tag points to an array of locale IDs. It allows you to
  261.             specify the text contents of the gadgets using locale. The array
  262.             must be terminated with a 0 value. You can use this instead of
  263.             the GTCY_Labels or GTMX_Labels tags.
  264.  
  265.  
  266.             GTCustom_Image - (struct Image *)
  267.  
  268.             Used with : BUTTON_KIND
  269.  
  270.             Points to an Image structure that defines an image to be displayed
  271.             within the button.
  272.  
  273.  
  274.             GTCustom_CallBack - (void __asm (*)(register __a1 struct TagItem *,
  275.                                                 register __a2 struct Window *))
  276.  
  277.             Used with : All types
  278.  
  279.             This tag allows you to specify the address of a callback function
  280.             that is called when the object is added to the window via
  281.             AddObjectList(). The callback function is passed both the window
  282.             pointer and a pointer to the tag. The function can modify both the
  283.             ti_Tag and ti_Data values of the tag, and when it returns the
  284.             Tag will be re-evaluated with the new contents.
  285.  
  286.  
  287.             GTCustom_LayoutRel - USHORT
  288.  
  289.             Used with : All types
  290.  
  291.             Lets you position objects relative to another. The ti_Data field
  292.             contains the ID of an object that *has previously been added*
  293.             (eg is before this one in the ObjectDef array). The new object
  294.             will be positioned relative to the specified object; from the
  295.             new object's point of view, coordinate 0,0 is the top-left
  296.             corner of the relative object. You can use POS_CENTER and the
  297.             other magic position values with this tag. For example, to
  298.             position an object in the center of another one, you would
  299.             use the GTCustom_LayoutRel tag, and set char_dims.Left and
  300.             char_dims.Top for the new object to POS_CENTER.
  301.  
  302.             If the window is resizeable, you must supply the GTCustom_CopyTags
  303.             tag as well.
  304.             
  305.  
  306.             GTCustom_LayoutPos - USHORT
  307.  
  308.             Used with : All types
  309.  
  310.             Lets you position objects based on the position of another object.
  311.             The ti_Data field contains the ID of an object that must have been
  312.             previously added. This tag is used in conjunction with the
  313.             following object flags:
  314.  
  315.                 POSFLAG_ADJUST_POS_X    - X-position is relative to X-position
  316.                                           of other object
  317.  
  318.                 POSFLAG_ADJUST_POS_Y    - Y-position is relative to Y-position
  319.                                           of other object
  320.  
  321.                 POSFLAG_ALIGN_X         - Align X-position with other object
  322.  
  323.                 POSFLAG_ALIGN_Y         - Align Y-position with other object
  324.  
  325.             If the window is resizeable, you must supply the GTCustom_CopyTags
  326.             tag when you supply this tag.
  327.  
  328.  
  329.             GTCustom_Control - USHORT
  330.  
  331.             Used with : CHECKBOX_KIND, FILE_BUTTON_KIND, DIR_BUTTON_KIND,
  332.                         FONT_BUTTON_KIND
  333.  
  334.             Specifies another gadget that this gadget controls. The ti_Data
  335.             field contains the ID of the other gadget. For CHECKBOX_KIND
  336.             gadgets, the other gadget will be disabled when the checkbox
  337.             is deselected, and enabled when it is selected. For the other
  338.             types of gadget, the other gadget MUST be a STRING_KIND, into
  339.             which will go the pathname that was selected by the file requester.
  340.  
  341.             For FONT_BUTTON_KIND gadgets, the font name is copied into the
  342.             STRING_KIND gadget specified with this tag, and the font size is
  343.             copied into an INTEGER_KIND gadget with the control ID + 1.
  344.  
  345.  
  346.             GTCustom_TextAttr - struct TextAttr *
  347.  
  348.             Used with : All gadgets
  349.  
  350.             Lets you specify the font that will be used for a specific gadget.
  351.  
  352.  
  353.             GTCustom_MinMax - ULONG
  354.  
  355.             Used with : SLIDER_KIND, INTEGER_KIND, SCROLLER_KIND
  356.  
  357.             Allows you to specify the minimum and maximum values of a gadget.
  358.             The ULONG contains the maximum value in the upper 16 bits and the
  359.             minimum value in the lower 16 bits. For SLIDER_KIND and
  360.             SCROLLER_KIND, you can also use the GadTools equivalent tags.
  361.  
  362.  
  363.             GTCustom_ThinBorders - BOOL
  364.  
  365.             Used with : BUTTON_KIND, CHECKBOX_KIND, FRAME_KIND, NUMBER_KIND,
  366.                         TEXT_KIND, PALETTE_KIND, FILE_BUTTON_KIND,
  367.                         DIR_BUTTON_KIND and FONT_BUTTON_KIND
  368.  
  369.             This tag can be used instead of the BUTTONFLAG_THIN_BORDERS flag.
  370.             This tag also allows you to control thin borders when accessing
  371.             the Opus BOOPSI gadgets directly.
  372.  
  373.  
  374.             GTCustom_Borderless - BOOL
  375.  
  376.             Used with : BUTTON_KIND, CHECKBOX_KIND, FRAME_KIND, NUMBER_KIND,
  377.                         TEXT_KIND, PALETTE_KIND, FILE_BUTTON_KIND,
  378.                         DIR_BUTTON_KIND and FONT_BUTTON_KIND
  379.  
  380.             If set to TRUE, this causes the gadget to be rendered without
  381.             a border.
  382.  
  383.  
  384.             GTCustom_LocaleKey - ULONG
  385.  
  386.             Used with : All gadgets
  387.  
  388.             This tag takes a locale ID, and uses the corresponding string to
  389.             set the key equivalent for this gadget. The string is searched
  390.             for the first underscore character, and the character immediately
  391.             after the underscore is used as the key equivalent.
  392.  
  393.  
  394.             GTCustom_NoSelectNext - BOOL
  395.  
  396.             Used with : STRING_KIND, INTEGER_KIND
  397.  
  398.             Ordinarily, pressing return in a string field causes the cursor
  399.             to move to the next field automatically. If you specify TRUE for
  400.             this tag, pressing return will simply deactivate the current field.
  401.  
  402.  
  403.             GTCustom_PathFilter - BOOL
  404.  
  405.             Used with : STRING_KIND
  406.  
  407.             If you specify TRUE for this tag, the string field will
  408.             automatically filter the / and : path characters out.
  409.  
  410.  
  411.             GTCustom_Secure - BOOL
  412.  
  413.             Used with : STRING_KIND
  414.  
  415.             If you specify TRUE for this tag, the string field will operate
  416.             in secure "password" mode.
  417.  
  418.  
  419.             GTCustom_History - Att_List *
  420.  
  421.             Used with : STRING_KIND, INTEGER_KIND
  422.  
  423.             Lets you specify a history list for the gadget. See the docs
  424.             for the EH_History tag under GetEditHook() for more information.
  425.  
  426.  
  427.             GTCustom_CopyTags - BOOL
  428.  
  429.             Used with : All types
  430.  
  431.             If you specify TRUE for this tag, the supplied tag list will be
  432.             copied when the object is created. You need to specify this tag
  433.             in conjunction with other tags, depending on the situation.
  434.  
  435.  
  436.             GTCustom_FontPens - ULONG *
  437.  
  438.             Used with : FONT_BUTTON_KIND
  439.  
  440.             The ti_Data field must point to a ULONG that will be used to
  441.             store the front pen, back pen and draw mode result from the
  442.             font requester. The data is stored with FgPen in the lowest
  443.             byte, BgPen in the second byte and DrawMode in the third
  444.             byte. The most significant byte is not used. You must supply
  445.             the GTCustom_CopyTags tag if you use this tag.
  446.  
  447.  
  448.             GTCustom_FontPenCount - short
  449.  
  450.             Used with : FONT_BUTTON_KIND (only under ASL v39.9)
  451.  
  452.             This allows you to specify the number of pens displayed in the
  453.             font requester. It is used in conjunction with the
  454.             GTCustom_FontPenTable tag, and the GTCustom_CopyTags tag must
  455.             also be supplied.
  456.  
  457.  
  458.             GTCustom_FontPenTable - UBYTE *
  459.  
  460.             Used with : FONT_BUTTON_KIND (only under ASL v39.9)
  461.  
  462.             This is used with GTCustom_FontPenCount. The ti_Data field points
  463.             to a UBYTE array of pen numbers to display in the font requester.
  464.             You must also specify the GTCustom_CopyTags tag.
  465.  
  466.  
  467.             GTCustom_Bold - BOOL
  468.  
  469.             Used with : BUTTON_KIND, CHECKBOX_KIND, FRAME_KIND, NUMBER_KIND,
  470.                         TEXT_KIND, PALETTE_KIND, FILE_BUTTON_KIND,
  471.                         DIR_BUTTON_KIND and FONT_BUTTON_KIND
  472.  
  473.             If set to TRUE, this tag causes the label for the button to be
  474.             rendered in bold. Use GTCustom_Style for greater control.
  475.  
  476.  
  477.             GTCustom_NoGhost - BOOL
  478.  
  479.             Used with : BUTTON_KIND, CHECKBOX_KIND, FRAME_KIND, NUMBER_KIND,
  480.                         TEXT_KIND, PALETTE_KIND, FILE_BUTTON_KIND,
  481.                         DIR_BUTTON_KIND and FONT_BUTTON_KIND
  482.  
  483.             If set to TRUE, when the button is disabled its image will not
  484.             be ghosted.
  485.  
  486.  
  487.             GTCustom_Style - ULONG
  488.  
  489.             Used with : BUTTON_KIND, CHECKBOX_KIND, FRAME_KIND, NUMBER_KIND,
  490.                         TEXT_KIND, PALETTE_KIND, FILE_BUTTON_KIND,
  491.                         DIR_BUTTON_KIND and FONT_BUTTON_KIND
  492.  
  493.             This tag allows you to control the text style used to render the
  494.             button label. Valid flags for the style are FSF_BOLD and
  495.             FSF_ITALIC.
  496.  
  497.  
  498.             GTCustom_FrameFlags - ULONG
  499.  
  500.             Used with : FRAME_KIND
  501.  
  502.             This tag lets you specify the type of frame rendered for the
  503.             frame gadget. Currently the only value valid is AREAFLAG_RECESSED,
  504.             to specify a recessed frame.
  505.  
  506.  
  507.             GTCustom_ChangeSigTask - struct Task *
  508.  
  509.             Used with : STRING_KIND, INTEGER_KIND
  510.  
  511.             This tag lets you specify a Task that is to be signalled whenever
  512.             the contents of the string gadget change.
  513.  
  514.  
  515.             GTCustom_ChangeSigBit - short
  516.  
  517.             Used with : STRING_KIND, INTEGER_KIND
  518.  
  519.             This tag lets you specify the bit that a task is signalled with
  520.             whenever the contents of the string gadget change.
  521.  
  522.  
  523.             GTCustom_Justify - short
  524.  
  525.             Used with : TEXT_KIND, NUMBER_KIND
  526.  
  527.             This tag lets you specify the justification of the text displayed
  528.             in the gadget. Valid values are JUSTIFY_CENTER (the default),
  529.             JUSTIFY_LEFT and JUSTIFY_RIGHT.
  530.  
  531.         In addition to these tags, OPUS_LISTVIEW_KIND gadgets (via the Opus
  532.         BOOPSI listview class) supports several additional tags. See the
  533.         section on the listview class for information on these.
  534.  
  535.  
  536.     The last member in an array of ObjectDef structures must have a od_Type
  537. of OD_END set.
  538.  
  539.  
  540. 3.  The layout routines can only add gadgets to a special sort of window; one
  541. that has been created with the OpenConfigWindow() call. Two structures are
  542. needed to open one of these windows. The first, a ConfigWindow structure,
  543. specifies the position and size of the new window. It has cw_CharDims and
  544. cw_FineDims fields, analagous to the fields in ObjectDef structures.
  545.  
  546.     The second is a NewConfigWindow structure. This is initialised as follows:
  547.  
  548.         nw_Parent
  549.  
  550.         This field points to the parent of the Window. The parent can be
  551.         either another window (the default) or a screen (if the
  552.         WINDOWF_SCREEN_PARENT flag is set).
  553.  
  554.  
  555.         nw_Dims
  556.  
  557.         This points to the ConfigWindow structure used to define the size
  558.         of the new window.
  559.  
  560.  
  561.         nw_Title
  562.  
  563.         This points to a title string for the new window.
  564.  
  565.  
  566.         nw_Locale
  567.  
  568.         This points to a valid DOpusLocale structure for the window. All
  569.         ObjectDefs that use a locale ID will obtain their strings via this
  570.         structure.
  571.  
  572.  
  573.         nw_Port
  574.  
  575.         Allows you to specify a message port to use; you should set this to
  576.         NULL.
  577.  
  578.  
  579.         nw_Flags
  580.  
  581.         Control flags. Valid values are:
  582.  
  583.             WINDOW_SCREEN_PARENT    - nw_Parent points to a Screen
  584.             WINDOW_NO_CLOSE         - no close gadget on the window
  585.             WINDOW_NO_BORDER        - borderless window
  586.             WINDOW_SIMPLE           - simplerefresh window
  587.             WINDOW_AUTO_REFRESH     - use with WINDOW_SIMPLE
  588.             WINDOW_AUTO_KEYS        - handle keypresses automatically
  589.             WINDOW_REQ_FILL         - backfill the window with stipple pattern
  590.             WINDOW_NO_ACTIVATE      - don't activate the window on open
  591.             WINDOW_VISITOR          - open as a visitor window
  592.             WINDOW_SIZE_RIGHT       - size gadget in right border
  593.             WINDOW_SIZE_BOTTOM      - size gadget in bottom border
  594.             WINDOW_ICONIFY          - iconify gadget in title bar
  595.  
  596.  
  597.         nw_Font
  598.  
  599.         Allows you to specify a font to use for the window. If NULL, the
  600.         current screen font will be used.
  601.  
  602. dopus5.library/AddObjectList                     dopus5.library/AddObjectList
  603.  
  604.     NAME
  605.         AddObjectList - add a list of objects to a window
  606.  
  607.     SYNOPSIS
  608.         AddObjectList(window, objects)
  609.                         A0       A1
  610.  
  611.         ObjectList *AddObjectList(struct Window *, ObjectDef *);
  612.  
  613.     FUNCTION
  614.         This function adds a list of objects to a window. The window must have
  615.         previously been opened with the OpenConfigWindow() call.
  616.  
  617.     INPUTS
  618.         window - window to add the objects to
  619.         objects - array of objects to add
  620.  
  621.     RESULT
  622.         Returns a pointer to the list of created objects, or NULL for failure.
  623.  
  624.     NOTES
  625.         You can add multiple object lists to a window with multiple calls to
  626.         AddObjectList(). These lists are chained together, and as long as
  627.         you pass the address of the FIRST object list to any functions that
  628.         search an object list, all chained lists will be searched
  629.         automatically.
  630.  
  631.     SEE ALSO
  632.         OpenConfigWindow(), SetGadgetValue()
  633.  
  634. dopus5.library/AddWindowMenus                   dopus5.library/AddWindowMenus
  635.  
  636.     NAME
  637.         AddWindowMenus - add menus to a window
  638.  
  639.     SYNOPSIS
  640.         AddWindowMenus(window, menus)
  641.                          A0     A1
  642.  
  643.         void AddWindowMenus(struct Window *, MenuData *);
  644.  
  645.     FUNCTION
  646.         This function makes it easy to add menus to a window opened via
  647.         OpenConfigWindow(). Even if you don't use the AddObjectList() routine
  648.         to add gadgets to the window, you can still use this call to add
  649.         menus.
  650.  
  651.         AddWindowMenus() takes an array of MenuData structures, and constructs
  652.         and initialises the Intuition Menu structures automatically. The
  653.         MenuData structures are initialised as follows:
  654.  
  655.             md_Type     - entry type; NM_TITLE, NM_ITEM or NM_SUB. The array
  656.                           must be terminated by an NM_END item.
  657.  
  658.             md_ID       - the ID value for the menu item.
  659.  
  660.             md_Name     - the name of the menu item. This can either be a
  661.                           locale ID, or, if the MENUFLAG_TEXT_STRING flag is
  662.                           set, a pointer to a real string.
  663.  
  664.             md_Flags    - control flags.
  665.  
  666.         The md_Flags field supports the standard Intuition and GadTools menu
  667.         flags as well as several custom flags:
  668.  
  669.             MENUFLAG_TEXT_STRING - md_Name is a real string
  670.             MENUFLAG_COMM_SEQ    - the menu will be given a command sequence
  671.                                    (Right-Amiga + a key)
  672.             MENUFLAG_AUTO_MUTEX  - automatic mutual exclusion
  673.  
  674.         If MENUFLAG_COMM_SEQ is specified, the key used for the command
  675.         sequence is normally the first character of the menu name. However,
  676.         you can specify a character to use instead of this, by setting the
  677.         MENUFLAG_USE_SEQ flag, and using the MENUFLAG_MAKE_SEQ() macro.
  678.         For example, to specify a command sequence of Right Amiga and A, you
  679.         would use :
  680.  
  681.             MENUFLAG_COMM_SEQ|MENUFLAG_USE_SEQ|MENUFLAG_MAKE_SEQ('A')
  682.  
  683.         The automatic mutual exclusion works on all items at the current
  684.         level that have the CHECKIT flag set.
  685.  
  686.     INPUTS
  687.         window - window to add menus to
  688.         menus - array of MenuData structures, terminated with NM_END
  689.  
  690.     RESULT
  691.         The menus are added to the window. You can check if this operation
  692.         failed (through lack of memory) by examining the window->MenuStrip
  693.         pointer; if NULL, the window has no menus.
  694.  
  695.     SEE ALSO
  696.         FindMenuItem(), FreeWindowMenus()
  697.  
  698. dopus5.library/BoundsCheckGadget             dopus5.library/BoundsCheckGadget
  699.  
  700.     NAME
  701.         BoundsCheckGadget - bounds check an integer gadget
  702.  
  703.     SYNOPSIS
  704.         BoundsCheckGadget(list, id, min, max)
  705.                            A0   D0   D1   D2
  706.  
  707.         long BoundsCheckGadget(ObjectList *, ULONG, long, long);
  708.  
  709.     FUNCTION
  710.         This routine tests the value of an integer gadget against the supplied
  711.         minimum and maximum, adjusts and refreshes it if it is invalid, and
  712.         returns the new value.
  713.  
  714.     INPUTS
  715.         list - ObjectList containing the gadget
  716.         id - gadget ID
  717.         min - minimum value
  718.         max - maximum value
  719.  
  720.     RESULT
  721.         Returns the new value of the gadget.
  722.  
  723. dopus5.library/BuildMenuStrip                   dopus5.library/BuildMenuStrip
  724.  
  725.     NAME
  726.         BuildMenuStrip - build a MenuStrip easily
  727.  
  728.     SYNOPSIS
  729.         BuildMenuStrip(menus, locale)
  730.                          A0     A1
  731.  
  732.         struct Menu *BuildMenuStrip(MenuData *, struct DOpusLocale *);
  733.  
  734.     FUNCTION
  735.         This routine takes the supplied MenuData array, and returns an
  736.         initialised menu strip. This menu strip can then be layed out
  737.         using the LayoutMenus() function in gadtools.library, and added
  738.         to any window.
  739.  
  740.     INPUTS
  741.         menus - array of MenuData structures
  742.         locale - locale to use for text strings
  743.  
  744.     RESULT
  745.         Returns a pointer to the head of the menu strip.
  746.  
  747.     NOTES
  748.         The menus returned by this function can be used on any window. If
  749.         your window was opened with OpenConfigWindow(), you should use the
  750.         AddWindowMenus() function instead of this one.
  751.  
  752.         The returned menu strip can be freed with a call to FreeMenus() in
  753.         gadtools.library.
  754.  
  755.         See the instructions for AddWindowMenus() for information about
  756.         initialising the MenuData structures.
  757.  
  758.     SEE ALSO
  759.         AddWindowMenus(), gadtools.library/LayoutMenusA(),
  760.         gadtools.library/FreeMenus()
  761.  
  762. dopus5.library/CheckObjectArea                 dopus5.library/CheckObjectArea
  763.  
  764.     NAME
  765.         CheckObjectArea - check if a point is within an object's area
  766.  
  767.     SYNOPSIS
  768.         CheckObjectArea(object, x, y)
  769.                           A0   D0 D1
  770.  
  771.         BOOL CheckObjectArea(GL_Object *, long, long);
  772.  
  773.     FUNCTION
  774.         This routine tests if the coordinate is within the "select" area of
  775.         the object.
  776.  
  777.     INPUTS
  778.         object - object to test
  779.         x - x coordinate
  780.         y - y coordinate
  781.  
  782.     RESULT
  783.         Returns TRUE if the point falls within the object.
  784.  
  785. dopus5.library/ClearWindowBusy                 dopus5.library/ClearWindowBusy
  786.  
  787.     NAME
  788.         ClearWindowBusy - make a window unbusy
  789.  
  790.     SYNOPSIS
  791.         ClearWindowBusy(window)
  792.                           A0
  793.  
  794.         void ClearWindowBusy(struct Window *);
  795.  
  796.     FUNCTION
  797.         This routine undoes the effect of a SetWindowBusy() call. The mouse
  798.         pointer of the window is returned to normal, and input is unblocked.
  799.  
  800.     INPUTS
  801.         window - the window in question
  802.  
  803.     SEE ALSO
  804.         SetWindowBusy()
  805.  
  806. dopus5.library/CloseConfigWindow             dopus5.library/CloseConfigWindow
  807.  
  808.     NAME
  809.         CloseConfigWindow - close a window
  810.  
  811.     SYNOPSIS
  812.         CloseConfigWindow(window)
  813.                             A0
  814.  
  815.         void CloseConfigWindow(struct Window *);
  816.  
  817.     FUNCTION
  818.         This function closes a window that was opened with a call to
  819.         OpenConfigWindow(). All memory associated with the window, including
  820.         object lists, menus and memory allocated from the window's memory
  821.         pool is freed by this call.
  822.  
  823.     INPUTS
  824.         window - window to close. MUST have been opened with OpenConfigWindow()
  825.  
  826.     RESULT
  827.         The window is closed.
  828.  
  829.     SEE ALSO
  830.         OpenConfigWindow()
  831.  
  832. dopus5.library/DisableObject                     dopus5.library/DisableObject
  833.  
  834.     NAME
  835.         DisableObject - disable/enable an object
  836.  
  837.     SYNOPSIS
  838.         DisableObject(list, id, state)
  839.                        A0   D0    D1
  840.  
  841.         void DisableObject(ObjectList *, ULONG, BOOL);
  842.  
  843.     FUNCTION
  844.         This routine disables or enables an object. Currently, only gadgets
  845.         support being disabled.
  846.  
  847.     INPUTS
  848.         list - ObjectList containing object
  849.         id - object ID
  850.         state - TRUE for disable, FALSE for enable
  851.  
  852.     RESULT
  853.         The object is disabled or enabled.
  854.  
  855. dopus5.library/DisplayObject                     dopus5.library/DisplayObject
  856.  
  857.     NAME
  858.         DisplayObject - redisplay an object
  859.  
  860.     SYNOPSIS
  861.         DisplayObject(window, object, fpen, bpen, text)
  862.                         A0      A1     D0    D1    A2
  863.  
  864.         void DisplayObject(struct Window *, GL_Object *, long, long, char *);
  865.  
  866.     FUNCTION
  867.         This routine lets you change and refresh an object. Currently, it is
  868.         only used for OD_TEXT and OD_AREA objects.
  869.  
  870.     INPUTS
  871.         window - window containing the object
  872.         object - object to display
  873.         fpen - new foreground pen, -1 for no change
  874.         bpen - new background pen, -1 for no change
  875.         text - new text
  876.  
  877.     RESULT
  878.         The display is refreshed immediately.
  879.  
  880. dopus5.library/EndRefreshConfigWindow   dopus5.library/EndRefreshConfigWindow
  881.  
  882.     NAME
  883.         EndRefreshConfigWindow - finish refreshing a config window
  884.  
  885.     SYNOPSIS
  886.         EndRefreshConfigWindow(window)
  887.                                  A0
  888.  
  889.         void EndRefreshConfigWindow(struct Window *);
  890.  
  891.     FUNCTION
  892.         This is analagous to calling GT_EndRefresh(window,TRUE) on the
  893.         window. It finishes and cleans up the refresh process begun with
  894.         StartRefreshConfigWindow().
  895.  
  896.     INPUTS
  897.         window - window to end refresh of
  898.  
  899.     NOTES
  900.         If you are using a smart refresh window, or have set the
  901.         WINDOW_AUTO_REFRESH flag, you will not need to call this function.
  902.  
  903.     SEE ALSO
  904.         StartRefreshConfigWindow(), gadtools.library/GT_EndRefresh()
  905.  
  906. dopus5.library/FindMenuItem                       dopus5.library/FindMenuItem
  907.  
  908.     NAME
  909.         FindMenuItem - find a menu item by ID
  910.  
  911.     SYNOPSIS
  912.         FindMenuItem(menu, id)
  913.                       A0   D0
  914.  
  915.         struct MenuItem *FindMenuItem(struct Menu *, USHORT);
  916.  
  917.     FUNCTION
  918.         Traverses the menu list from the supplied pointer, searching for
  919.         a menu with the given ID. This ID is extracted using the
  920.         GTMENUITEM_USERDATA() macro. If you constructed the menu item
  921.         with AddWindowMenus() or BuildMenuStrip(), the ID was supplied
  922.         in the md_ID field of the MenuData structure.
  923.  
  924.     INPUTS
  925.         menu - Menu to start search
  926.         id - ID to search for
  927.  
  928.     RESULT
  929.         Returns a pointer to the MenuItem or NULL if not found.
  930.  
  931.     SEE ALSO
  932.         AddWindowMenus(), BuildMenuStrip()
  933.  
  934. dopus5.library/FreeObjectList                   dopus5.library/FreeObjectList
  935.  
  936.     NAME
  937.         FreeObjectList - free a list of objects
  938.  
  939.     SYNOPSIS
  940.         FreeObjectList(list)
  941.                         A0
  942.  
  943.         void FreeObjectList(ObjectList *);
  944.  
  945.     FUNCTION
  946.         This routine frees the supplied list of objects. If there are any
  947.         gadgets in the list, they are automatically removed from the window
  948.         before being freed.
  949.  
  950.         Ordinarily you do not need to call this function; any existing objects
  951.         are freed automatically when you close the window with
  952.         CloseConfigWindow(). However, this function together with
  953.         AddObjectList() allows you to add and remove objects (gadgets) from
  954.         the window dynamically. This is something that is not possible under
  955.         GadTools.
  956.  
  957.     INPUTS
  958.         list - object list to free
  959.  
  960.     RESULT
  961.         The list is delinked and all its objects are freed. If you are freeing
  962.         just one list from a window, you will need to refresh the display
  963.         after you have freed the objects.
  964.  
  965.     SEE ALSO
  966.         AddObjectList(), CloseConfigWindow()
  967.  
  968. dopus5.library/FreeWindowMenus                 dopus5.library/FreeWindowMenus
  969.  
  970.     NAME
  971.         FreeWindowMenus - free menus from a window
  972.  
  973.     SYNOPSIS
  974.         FreeWindowMenus(window)
  975.                           A0
  976.  
  977.         void FreeWindowMenus(struct Window *);
  978.  
  979.     FUNCTION
  980.         Frees the menus that were attached with a call to AddWindowMenus().
  981.         Normally you do not need to call this function, as menus are
  982.         automatically freed when you close the window with CloseConfigWindow().
  983.  
  984.     INPUTS
  985.         window - window to free menus for
  986.  
  987.     RESULT
  988.         The menus are removed from the window and freed.
  989.  
  990.     SEE ALSO    
  991.         AddWindowMenus()
  992.  
  993. dopus5.library/GetGadgetValue                   dopus5.library/GetGadgetValue
  994.  
  995.     NAME
  996.         GetGadgetValue - get the value of a gadget
  997.  
  998.     SYNOPSIS
  999.         GetGadgetValue(list, id)
  1000.                         A0   A1
  1001.  
  1002.         long GetGadgetValue(ObjectList *, USHORT);
  1003.  
  1004.     FUNCTION
  1005.         This returns the current value of the gadget, specified by gadget ID.
  1006.         The supplied list is searched for the gadget.
  1007.  
  1008.     INPUTS
  1009.         list - ObjectList containing the gadget
  1010.         id - gadget ID
  1011.  
  1012.     RESULT
  1013.         Returns the current value of the gadget. The contents of the return
  1014.         value are dependant on the type of gadget:
  1015.  
  1016.             BUTTON_KIND     - if the BUTTONFLAG_TOGGLE_SELECT flag was set,
  1017.                               returns TRUE or FALSE to indicate the state of
  1018.                               the gadget.
  1019.  
  1020.             MX_KIND
  1021.             CYCLE_KIND
  1022.             OPUS_LISTVIEW_KIND
  1023.             LISTVIEW_KIND
  1024.             SLIDER_KIND
  1025.             SCROLLER_KIND
  1026.             PALETTE_KIND    - returns the current selection or value
  1027.  
  1028.             CHECKBOX_KIND   - returns TRUE or FALSE to indicate the state
  1029.                               of the gadget.
  1030.  
  1031.             INTEGER_KIND    - returns the integer value of the gadget
  1032.  
  1033.             STRING_KIND     - returns a pointer to the string contents. This
  1034.                               pointer is READ ONLY!
  1035.  
  1036.     SEE ALSO
  1037.         SetGadgetValue()
  1038.  
  1039. dopus5.library/GetObject                             dopus5.library/GetObject
  1040.  
  1041.     NAME
  1042.         GetObject - get an object by ID from a list
  1043.  
  1044.     SYNOPSIS
  1045.         GetObject(list, id)
  1046.                    A0   D0
  1047.  
  1048.         GL_Object *GetObject(ObjectList *, ULONG);
  1049.  
  1050.     FUNCTION
  1051.         Searches the supplied object list (and any chained lists) for the
  1052.         object with the given ID value.
  1053.  
  1054.     INPUTS
  1055.         list - ObjectList to search
  1056.         id - ID to search for
  1057.  
  1058.     RESULT
  1059.         Returns a pointer to the object or NULL if not found.
  1060.  
  1061.     SEE ALSo
  1062.         AddObjectList()
  1063.  
  1064. dopus5.library/GetObjectRect                     dopus5.library/GetObjectRect
  1065.  
  1066.     NAME
  1067.         GetObjectRect - get an object's rectangle
  1068.  
  1069.     SYNOPSIS
  1070.         GetObjectRect(list, id, rect)
  1071.                        A0   D0   A1
  1072.  
  1073.         BOOL GetObjectRect(ObjectList *, ULONG, struct Rectangle *);
  1074.  
  1075.     FUNCTION
  1076.         Searches for the object, and if found, copies the coordinates of the    
  1077.         object's display rectangle into the supplied structure.
  1078.  
  1079.     INPUTS
  1080.         list - ObjectList containing the object
  1081.         id - ID of the object
  1082.         rect - Rectangle structure for result
  1083.  
  1084.     RESULT
  1085.         Returns FALSE if the object could not be found.
  1086.  
  1087. dopus5.library/GetWindowAppPort               dopus5.library/GetWindowAppPort
  1088.  
  1089.     NAME
  1090.         GetWindowAppPort - get a window's application port
  1091.  
  1092.     SYNOPSIS
  1093.         GetWindowAppPort(window)
  1094.                            A0
  1095.  
  1096.         struct MsgPort *GetWindowAppPort(struct Window *);
  1097.  
  1098.     FUNCTION
  1099.         If a window has registered itself with a call to SetWindowID(), this
  1100.         function will return the address of its application message port.
  1101.  
  1102.     INPUTS
  1103.         window - window in question
  1104.  
  1105.     RESULT
  1106.         Returns a pointer to the message port, or NULL if the window wasn't
  1107.         registered.
  1108.  
  1109.     SEE ALSO
  1110.         SetWindowID(), GetWindowID()
  1111.  
  1112. dopus5.library/GetWindowID                         dopus5.library/GetWindowID
  1113.  
  1114.     NAME
  1115.         GetWindowID - get a window's ID code
  1116.  
  1117.     SYNOPSIS
  1118.         GetWindowID(window)
  1119.                       A0
  1120.  
  1121.         ULONG GetWindowID(struct Window *);
  1122.  
  1123.     FUNCTION
  1124.         If a window has been registered with SetWindowID(), this function
  1125.         returns the ID code.
  1126.  
  1127.     INPUTS
  1128.         window - window in question
  1129.  
  1130.     RESULT
  1131.         Returns the ID code of the window if it is registered. Returns
  1132.         WINDOW_UNKNOWN if not registered. Returns WINDOW_UNDEFINED if the
  1133.         Window is registered, but does not have an ID or application port.
  1134.  
  1135.     SEE ALSO
  1136.         SetWindowID(), GetWindowAppPort()
  1137.  
  1138. dopus5.library/GetWindowMsg                       dopus5.library/GetWindowMsg
  1139.  
  1140.     NAME
  1141.         GetWindowMsg - get IntuiMessage for a window
  1142.  
  1143.     SYNOPSIS
  1144.         GetWindowMsg(port)
  1145.                       A0
  1146.  
  1147.         struct IntuiMessage *GetWindowMsg(struct MsgPort *);
  1148.  
  1149.     FUNCTION
  1150.         This routine is analagous to the GT_GetIMsg call under GadTools.
  1151.         It searches the supplied port for an IntuiMessage, performs
  1152.         pre-processing on the message and returns the result to you.
  1153.         It is highly recommended that you use this instead of a normal call
  1154.         to GetMsg() when using the layout routines. In particular, auto
  1155.         refreshing of simplerefresh windows, resizing, key equivalents and
  1156.         proper gadget processing will all be affected if you do not call
  1157.         this function.
  1158.  
  1159.     INPUTS
  1160.         port - port to search for messages (window->UserPort)
  1161.  
  1162.     RESULT
  1163.         Returns a pointer to the message, or NULL if there was none. You
  1164.         must call ReplyWindowMsg() to reply to messages from this function.
  1165.  
  1166.     SEE ALSO
  1167.         ReplyWindowMsg()
  1168.  
  1169. dopus5.library/LayoutResize                       dopus5.library/LayoutResize
  1170.  
  1171.     NAME
  1172.         LayoutResize - resize a window
  1173.  
  1174.     SYNOPSIS
  1175.         LayoutResize(window)
  1176.                        A0
  1177.  
  1178.         void LayoutResize(struct Window *);
  1179.  
  1180.     FUNCTION
  1181.         This routine is called to handle refreshing of a window when it is
  1182.         resized by the user. If you call GetWindowMsg() in your event loop,
  1183.         this is called automatically for you.
  1184.  
  1185.     INPUTS
  1186.         window - window that has been resized
  1187.  
  1188.     RESULT
  1189.         All objects in the window are resized (if they were defined with
  1190.         proportional or relative sizes) and refreshed.
  1191.  
  1192. dopus5.library/OpenConfigWindow               dopus5.library/OpenConfigWindow
  1193.  
  1194.     NAME
  1195.         OpenConfigWindow - open a window
  1196.  
  1197.     SYNOPSIS
  1198.         OpenConfigWindow(newwin)
  1199.                            A0
  1200.  
  1201.         struct Window *OpenConfigWindow(NewConfigWindow *);
  1202.  
  1203.     FUNCTION
  1204.         This routine opens the window defined by the suppled NewConfigWindow
  1205.         structure.
  1206.  
  1207.     INPUTS
  1208.         newwin - initialised NewConfigWindow structure
  1209.  
  1210.     RESULT
  1211.         Returns a pointer to the Window. This is a normal Intuition window
  1212.         in most respects, but its UserData field points to a structure of
  1213.         additional information. You MUST NOT modify the UserData field of
  1214.         such a window.
  1215.  
  1216.     SEE ALSO
  1217.         AddObjectList(), CloseConfigWindow()
  1218.  
  1219. dopus5.library/ReplyWindowMsg                   dopus5.library/ReplyWindowMsg
  1220.  
  1221.     NAME
  1222.         ReplyWindowMsg - reply to a message
  1223.  
  1224.     SYNOPSIS
  1225.         ReplyWindowMsg(msg)
  1226.                         A0
  1227.  
  1228.         void ReplyWindowMsg(struct IntuiMessage *);
  1229.  
  1230.     FUNCTION
  1231.         Call this function to reply to a message you received via
  1232.         GetWindowMsg().
  1233.  
  1234.     INPUTS
  1235.         msg - message to reply to
  1236.  
  1237.     SEE ALSO
  1238.         GetWindowMsg()
  1239.  
  1240. dopus5.library/SetConfigWindowLimits     dopus5.library/SetConfigWindowLimits
  1241.  
  1242.     NAME
  1243.         SetConfigWindowLimits - set size limits for a window
  1244.  
  1245.     SYNOPSIS
  1246.         SetConfigWindowLimits(window, min, max)
  1247.                                 A0     A1   A2
  1248.  
  1249.         void SetConfigWindowLimits(struct Window *, ConfigWindow *,
  1250.                                                     ConfigWindow *);
  1251.  
  1252.     FUNCTION
  1253.         Sets the sizing limits of the supplied window. The minimum and
  1254.         maximum dimensions are specified with two ConfigWindow structures.
  1255.  
  1256.     INPUTS
  1257.         window - window to set limits for
  1258.         min - minimum dimensions
  1259.         max - maximum dimensions
  1260.  
  1261.     SEE ALSO
  1262.         OpenConfigWindow()
  1263.  
  1264. dopus5.library/SetGadgetChoices               dopus5.library/SetGadgetChoices
  1265.  
  1266.     NAME
  1267.         SetGadgetChoices - set the "choices" for a gadget
  1268.  
  1269.     SYNOPSIS
  1270.         SetGadgetChoices(list, id, choices)
  1271.                           A0   D0     A1
  1272.  
  1273.         void SetGadgetChoices(ObjectList *, ULONG, APTR);
  1274.  
  1275.     FUNCTION
  1276.         This routine sets the choices for a gadget. It operates differently for
  1277.         different types of gadgets:
  1278.  
  1279.             SCROLLER_KIND
  1280.  
  1281.             Sets the maximum value of the gadget, and adjusts the current value
  1282.             if it exceeds this limit.
  1283.  
  1284.             SLIDER_KIND
  1285.  
  1286.             Sets the minimum (lower 16 bits)  and maximum (upper 16 bits)
  1287.             values of the gadget, and adjusts the current value if it exceeds
  1288.             either of these limits.
  1289.  
  1290.             LISTVIEW_KIND/OPUS_LISTVIEW_KIND
  1291.  
  1292.             Sets the list contents pointer. This is either a struct List * or
  1293.             an Att_List *. If you set the value to NULL, the current list
  1294.             will be detached from the gadget and the list will be cleared.
  1295.             If you set the value to -1, the list will be detached but the
  1296.             gadget display will not be cleared.
  1297.  
  1298.             CYCLE_KIND
  1299.  
  1300.             Sets the cycle gadget contents. This points to a char * array, or
  1301.             NULL if you want the gadget to be empty. The array must be
  1302.             null-terminated.
  1303.  
  1304.     INPUTS
  1305.         list - ObjectList containing the gadget
  1306.         id - gadget ID
  1307.         choices - new choices for the gadget
  1308.  
  1309.     RESULT
  1310.         The display is updated immediately, if appropriate.
  1311.     
  1312. dopus5.library/SetGadgetValue                   dopus5.library/SetGadgetValue
  1313.  
  1314.     NAME
  1315.         SetGadgetValue - set the value of a gadget
  1316.  
  1317.     SYNOPSIS
  1318.         SetGadgetValue(list, id, value)
  1319.                         A0   D0    D1
  1320.  
  1321.         void SetGadgetValue(ObjectList *, USHORT, ULONG);
  1322.  
  1323.     FUNCTION
  1324.         Sets the value of a gadget. See the instructions for GetGadgetValue()
  1325.         for a list of the gadgets a value can be set for. Note that in the
  1326.         case of a STRING_KIND gadget, the string that you supply is copied,
  1327.         and does not need to remain valid once you have set it.
  1328.  
  1329.     INPUTS
  1330.         list - ObjectList containing the gadget
  1331.         id - gadget ID
  1332.         value - new value for the gadget
  1333.  
  1334.     RESULT
  1335.         The display is updated immediately.
  1336.  
  1337.     SEE ALSO
  1338.         GetGadgetValue()
  1339.  
  1340. dopus5.library/SetWindowBusy                     dopus5.library/SetWindowBusy
  1341.  
  1342.     NAME
  1343.         SetWindowBusy - make a window busy
  1344.  
  1345.     SYNOPSIS
  1346.         SetWindowBusy(window)
  1347.                         A0
  1348.  
  1349.         void SetWindowBusy(struct Window *);
  1350.  
  1351.     FUNCTION
  1352.         Makes the supplied window busy. The mouse pointer is changed to the
  1353.         system busy pointer, and all gadget input to the window is blocked.
  1354.         You must call ClearWindowBusy() to reverse this state.
  1355.  
  1356.     INPUTS
  1357.         window - window to make busy
  1358.  
  1359.     RESULT
  1360.         The window goes busy.
  1361.  
  1362.     NOTES
  1363.         You can only call this routine on a window opened with
  1364.         OpenConfigWindow().
  1365.  
  1366.     SEE ALSo
  1367.         OpenConfigWindow(), ClearWindowBusy()
  1368.  
  1369. dopus5.library/SetWindowID                         dopus5.library/SetWindowID
  1370.  
  1371.     NAME
  1372.         SetWindowID - register a window's ID
  1373.  
  1374.     SYNOPSIS
  1375.         SetWindowID(window, idptr, id, port)
  1376.                       A0      A1   D0   A2
  1377.  
  1378.         void SetWindowID(struct Window *, WindowID *, ULONG, struct MsgPort *);
  1379.  
  1380.     FUNCTION
  1381.         This routine "registers" a window, giving it an ID value and
  1382.         associating a message port with it.
  1383.  
  1384.         This is invaluable in a drag and drop situation, when you want to
  1385.         determine whether a particular window supports a particular type of
  1386.         drop operation.
  1387.  
  1388.         The function takes a pointer to a WindowID structure, which is stored
  1389.         in the UserData field of the Window. You therefore lose the use of the
  1390.         UserData field, but you can easily recover it by embedding a WindowID
  1391.         structure in a larger structure.
  1392.  
  1393.         It also takes an ID value, and a pointer to a message port. These
  1394.         values are retrievable with the GetWindowID() and GetWindowAppPort()
  1395.         calls.
  1396.  
  1397.         All windows opened with OpenConfigWindow() have an ID associated
  1398.         with them automatically; by default, the ID is set to WINDOW_UNDEFINED.
  1399.         If you wish to change it, you can use the SET_WINDOW_ID() macro.
  1400.  
  1401.     INPUTS
  1402.         window - window to register
  1403.         idptr  - pointer to WindowID structure. This MUST remain valid for the
  1404.                  life of the window
  1405.         id     - ID value for the window. You should set the WINDOW_USER bit
  1406.                  of any IDs you define.
  1407.         port   - pointer to message port. This does not actually have to be
  1408.                  a message port; it can be any 32 bit value.
  1409.  
  1410.     RESULT
  1411.         The window association is made.
  1412.  
  1413.     SEE ALSO
  1414.         GetWindowID(), GetWindowAppPort()
  1415.  
  1416. dopus5.library/StartRefreshConfigWindow dopus5.library/StartRefreshConfigWindow
  1417.  
  1418.     NAME
  1419.         StartRefreshConfigWindow - begin refreshing a window
  1420.  
  1421.     SYNOPSIS
  1422.         StartRefreshConfigWindow(window, finish)
  1423.                                    A0      D0
  1424.  
  1425.         void StartRefreshConfigWindow(struct Window *, long);
  1426.  
  1427.     FUNCTION
  1428.         This routine begins refresh of a simplerefresh window that was
  1429.         opened with OpenConfigWindow(). If you specify the WINDOW_AUTO_REFRESH
  1430.         flag, you will never need to call this function.
  1431.  
  1432.     INPUTS
  1433.         window - window to begin refreshing
  1434.         finish - if set to TRUE, the refresh is ended by this function too. Use
  1435.                  this if you don't want to do any rendering of your own for
  1436.                  the refresh (but if that's the case, why not just use
  1437.                  WINDOW_AUTO_REFRESH?)
  1438.  
  1439.     RESULT
  1440.         Refreshing is started (and optionally finished). All the objects in 
  1441.         the window will be refreshed.
  1442.  
  1443.     SEE ALSO
  1444.         EndRefreshConfigWindow(), intuition.library/BeginRefresh()
  1445.  
  1446.